Inside Macintosh: QuickTime
Each movie, track, and media can contain a user data list, which your application can use in any way you want. A user data list contains all the user data for a movie, track, or media. Each user data list may contain one or more user data items. All QuickTime user data items share several attributes.
First, each user data item carries a type identifier. This type is similar to a Resource Manager resource type, and is stored in a long integer. Apple has reserved all lowercase user data type values. You are free to create user data type values using uppercase letters. Apple recommends using type values that begin with the © character (Option-G) to specify user data items that store text data.
The following user data types are currently defined:
|
Indication of movie format (computer-generated, digitized, and so on) |
|
User data items of these types must contain text data only.
Second, the Movie Toolbox allows you to create more than one user data item in a user data list. Therefore, each user data item is identified by a unique index. Index values are assigned sequentially within a user data type and start at 1.
Finally, you may create alternate text for a given user data text item. For example, you may want to support multiple languages and may therefore want to create different text for each language. The Movie Toolbox allows you to specify different versions of the text of a single user data item. These versions are distinguished by their region code values.
The Movie Toolbox provides a number of functions that allow you to work with user data. Before you can work with the contents of a user data list, you must obtain a reference to the list. The GetMovieUserData , GetTrackUserData , or GetMediaUserData functions allow you to get a reference to a user data list. You can then use the GetUserData , AddUserData , and RemoveUserData functions to work with the items contained in the user data list. If your user data items contain text data, you can use the AddUserDataText , GetUserDataText , and RemoveUserDataText functions to work with the text of a user data item. Note that a single user data item can store either text or other data, but not both.
You can count the number of user data items of a specified type in a movie, track, or media by calling the CountUserDataType function. You can use the GetNextUserDataType function to scan all the types of user data in a specified user data list.
The Movie Toolbox also supplies a number of functions for the manipulation of user data. The SetUserDataItem and GetUserDataItem functions allow easy access to data stored in user data items. The NewUserData and DisposeUserData functions provide for the use of user data outside of the immediate context of QuickTime movies. Your applications and components can also create user data structures. The PutUserDataIntoHandle and the NewUserDataFromHandle functions permit user data to be stored and retrieved in a manner similar to public movies (also called atoms ). See the chapter "Movie Resource Formats" in this book for details on atoms.
The GetMovieUserData function allows your application to obtain access to a movie's user data list. You can then use the GetUserData , AddUserData , and RemoveUserData functions (described on GetUserData , AddUserData , and RemoveUserData , respectively) to manipulate the contents of the user data list. If the data list contains text data, you can use the GetUserDataText , AddUserDataText , and RemoveUserDataText functions (described on GetUserDataText , AddUserDataText , and RemoveUserDataText , respectively) to work with its contents.
pascal UserData GetMovieUserData (Movie theMovie);
The GetMovieUserData function returns a reference to the movie's user data list. This reference is valid until you dispose of the movie. When you save the movie, the Movie Toolbox saves the user data as well. If the function could not locate the movie's user data, it sets this returned value to nil .
You can use the GetMediaUserData function (described on GetMediaUserData ) to gain access to a media's user data. Similarly, you can use the GetTrackUserData function (described in the next section) to work with a track's user data.
The GetTrackUserData function allows your application to obtain access to a track's user data list. You can then use the GetUserData , AddUserData , and RemoveUserData functions (described on GetUserData , AddUserData , and RemoveUserData , respectively) to manipulate the contents of the user data list. If the data list contains text data, you can use the GetUserDataText , AddUserDataText , and RemoveUserDataText functions (described on GetUserDataText , AddUserDataText , and RemoveUserDataText , respectively) to work with its contents.
pascal UserData GetTrackUserData (Track theTrack);
The GetTrackUserData function returns a reference to the track's user data list. This reference is valid until you dispose of the track. When you save the track, the Movie Toolbox saves the user data as well. If the function could not locate the track's user data, it sets this returned value to nil .
You can use the GetMediaUserData function to gain access to a media's user data (described on GetMediaUserData ). Similarly, you can use the GetMovieUserData function (described on GetMovieUserData ) to work with a movie's user data.
The GetMediaUserData function allows your application to obtain access to a media's user data list. You can then use the GetUserData , AddUserData , and RemoveUserData functions (described on GetUserData , AddUserData , and RemoveUserData , respectively) to manipulate the contents of the user data list. If the data list contains text data, you can use the GetUserDataText , AddUserDataText , and RemoveUserDataText functions (described on GetUserDataText , AddUserDataText , and RemoveUserDataText , respectively) to work with its contents.
pascal UserData GetMediaUserData (Media theMedia);
The GetMediaUserData function returns a reference to the media's user data list. This reference is valid until you dispose of the media. When you save the media, the Movie Toolbox saves the user data as well. If the function could not locate the media's user data, it sets this returned value to nil .
You can use the GetMovieUserData function to gain access to a movie's user data (described on GetMovieUserData ). Similarly, you can use the GetTrackUserData function (described in the previous section) to work with a track's user data.
The GetNextUserDataType function allows you to retrieve the next user data type in a specified user data list. You can use this function to scan all the user data types in a user data list.
pascal long GetNextUserDataType (UserData theUserData,
OSType udType);
The CountUserDataType function allows you to determine the number of items of a given type in a user data list.
pascal short CountUserDataType (UserData theUserData,
OSType udType);
The AddUserData function allows your application to add an item to a user data list. You specify the user data list, the data to be added, and the data's type value.
pascal OSErr AddUserData (UserData theUserData,
Handle data, OSType udType);
The GetUserData function returns a specified user data item.
pascal OSErr GetUserData (UserData theUserData, Handle data,
OSType udType, long index);
The RemoveUserData function removes an item from a user data list. After the Movie Toolbox removes the item, it renumbers the remaining items of that type so that the index values are sequential and start at 1.
pascal OSErr RemoveUserData (UserData theUserData, OSType udType,
long index);
The AddUserDataText function allows your application to place language-tagged text into an item in a user data list. You specify the user data list and item, the data to be added, the data's type value, and the language code of the data.
pascal OSErr AddUserDataText (UserData theUserData, Handle data,
OSType udType, long index,
short itlRegionTag);
The Movie Toolbox places the specified data into the user data item. If the item does not exist when you call this function, the Movie Toolbox creates a new item for you (this is true only if the item you are adding is the first item in the list; otherwise, you must create the item yourself).
The GetUserDataText function allows your application to retrieve language-tagged text from an item in a user data list. You specify the user data list and item, and the item's type value and language code. The Movie Toolbox retrieves the specified text from the user data item.
pascal OSErr GetUserDataText (UserData theUserData, Handle data,
OSType udType, long index,
short itlRegionTag);
The RemoveUserDataText function allows your application to remove language-tagged text from an item in a user data list. You specify the user data list and item, and the item's type value and language code. The Movie Toolbox removes the specified text from the user data item.
pascal OSErr RemoveUserDataText (UserData theUserData,
OSType udType, long index,
short itlRegionTag);
The SetUserDataItem allows your application to set an item in a user data list. You specify the user data list, the data to be set, the size of the data to be set, and the data's type value.
pascal OSErr SetUserDataItem (UserData theUserData,
void *data, long size,
OSType udType, long index);
You must provide the size of the information specified in the data parameter because the data may be embedded inside a larger data structure or may be on the stack.
The SetUserDataItem function is a pointer-based version of AddUserData , which is described on AddUserData .
The GetUserDataItem function returns a specified user data item. GetUserDataItem is a pointer-based version of the GetUserData function, which is described on GetUserData .
pascal OSErr GetUserDataItem (UserData theUserData,
void *data, long size,
OSType udType, long index);
If the size field provided doesn't match the exact size of the actual user data item, an error is returned. In this case, you should use GetUserData instead. GetUserDataItem is useful for retrieving small, fixed-size pieces of user data without having to create a handle. You can pass 0 or 1 for the index parameter to indicate the first item.
The NewUserData function creates a new user data structure.
pascal OSErr NewUserData (UserData *theUserData);
You can manipulate the user data structure with any of the standard user data functions described in "Working With Movie User Data," . If the NewUserData function fails, the parameter theUserData is set to nil .
The DisposeUserData function disposes of a user data structure created by the NewUserData function.
pascal OSErr DisposeUserData (UserData theUserData);
Don't dispose of user data references obtained from the Movie Toolbox function GetMovieUserData , GetTrackUserData , or GetMediaUserData (described on GetMovieUserData , GetTrackUserData , and GetMediaUserData , respectively).
The PutUserDataIntoHandle function takes a specified user data structure and replaces the contents of the handle with a publicly parseable form of the user data.
pascal OSErr PutUserDataIntoHandle (UserData theUserData,
Handle h);
The NewUserDataFromHandle function creates a new user data structure from a handle.
pascal OSErr NewUserDataFromHandle (Handle h,
UserData *theUserData);